AuthZenService
[Experimental] Search for subjects with access to a resource
[Experimental] The SubjectSearch API returns all subjects that have a specific action (relation) on a given resource. This is useful for answering questions like “Who can read this document?” or “Who can administer this folder?”
Results can be filtered by subject type and support pagination for large result sets.
Examples
Find all users who can read a document
{
"resource": {"type": "document", "id": "roadmap"},
"action": {"name": "can_read"},
"subject": {"type": "user"}
}
Response:
{
"results": [
{"type": "user", "id": "anne"},
{"type": "user", "id": "bob"},
{"type": "user", "id": "charlie"}
],
"page": {"count": 3}
}
Paginated search with limit
{
"resource": {"type": "folder", "id": "engineering"},
"action": {"name": "can_view"},
"subject": {"type": "user"},
"page": {"limit": 10}
}
Continue from previous page
{
"resource": {"type": "folder", "id": "engineering"},
"action": {"name": "can_view"},
"subject": {"type": "user"},
"page": {"token": "eyJsYXN0X2lkIjoiMTAwIn0=", "limit": 10}
}
POST
/
stores
/
{store_id}
/
access
/
v1
/
search
/
subject
curl
# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/search/subject" \
-H "content-type: application/json" \
-d '{
"subject": {
"type": "user"
},
"action": {
"name": "reader"
},
"resource": {
"type": "document",
"id": "budget"
}
}'{
"page": {
"count": 123,
"next_token": "<string>",
"total": 123
},
"results": [
{
"id": "anne",
"type": "user",
"properties": {}
}
]
}{
"code": "validation_error",
"message": "Generic validation error"
}{
"code": "unauthenticated",
"message": "unauthenticated"
}{
"code": "forbidden",
"message": "the principal is not authorized to perform the action"
}{
"code": "undefined_endpoint",
"message": "Endpoint not enabled"
}{
"code": "10",
"message": "transaction conflict"
}{
"code": "throttled_timeout_error",
"message": "timeout due to throttling on complex request"
}{
"code": "internal_error",
"message": "Internal Server Error"
}Path Parameters
Body
application/json
Show child attributes
Show child attributes
Show child attributes
Show child attributes
REQUIRED by AuthZEN Subject Search. Subject id may be provided but is ignored.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Last modified on September 28, 2026
Was this page helpful?
⌘I
curl
# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/search/subject" \
-H "content-type: application/json" \
-d '{
"subject": {
"type": "user"
},
"action": {
"name": "reader"
},
"resource": {
"type": "document",
"id": "budget"
}
}'{
"page": {
"count": 123,
"next_token": "<string>",
"total": 123
},
"results": [
{
"id": "anne",
"type": "user",
"properties": {}
}
]
}{
"code": "validation_error",
"message": "Generic validation error"
}{
"code": "unauthenticated",
"message": "unauthenticated"
}{
"code": "forbidden",
"message": "the principal is not authorized to perform the action"
}{
"code": "undefined_endpoint",
"message": "Endpoint not enabled"
}{
"code": "10",
"message": "transaction conflict"
}{
"code": "throttled_timeout_error",
"message": "timeout due to throttling on complex request"
}{
"code": "internal_error",
"message": "Internal Server Error"
}